Summary

• When using --watch-path=<dir> together with --env-file=<path>, touching any file in the directory that contains the env file incorrectly triggers a restart — even if the changed file has nothing to do with the watched path
• Fix: filterFile() now watches the specific file directly in 'all' mode, rather than watching its entire parent directory

Root cause

FilesWatcher has two modes:

filterFile() in lib/internal/watch_mode/files_watcher.js:131 takes a shortcut on macOS and Windows (platforms with recursive fs.watch support): instead of setting up one watcher per file, it calls watchPath(dirname(file)) to watch the whole parent directory with a single recursive FSWatcher.

In 'filter' mode this is harmless — #onChange checks #filteredFiles before emitting 'changed', so only the tracked file triggers a restart.

In 'all' mode the filter check is skipped. So when watch_mode.js calls filterFile(resolve('.env')) (line 106) to watch the env file, it actually watches . (the CWD) recursively. Any fs.watch event in the CWD — including touch unrelated — then passes straight through and triggers a restart.

Fix

Add && this.#mode === 'filter' to the condition that selects the parent-directory strategy:

// Before
if (supportsRecursiveWatching) {
  this.watchPath(dirname(file));   // watches the whole directory

// After
if (supportsRecursiveWatching && this.#mode === 'filter') {
  this.watchPath(dirname(file));   // only in filter mode
} else {
  this.watchPath(file, false);     // watch the specific file
}

In 'all' mode the env file is now watched directly (watchPath(file, false)), so only changes to that exact file fire the watcher.

Tests

Two new cases added to test/parallel/test-watch-mode-files_watcher.mjs:

1. No false trigger: filterFile() in 'all' mode + modify an unrelated file in the same directory → mustNotCall asserts no 'changed' event fires
2. Correct trigger: filterFile() in 'all' mode + modify the watched file itself → 'changed' fires exactly once

Related

Ref: #61906 (reporter provided a clean minimal repro)

Fixes: #61906